.TH std::forward_list::splice_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::forward_list::splice_after \- std::forward_list::splice_after

.SH Synopsis
   void splice_after( const_iterator pos, forward_list& other );   \fB(1)\fP \fI(since C++11)\fP
   void splice_after( const_iterator pos, forward_list&& other );  \fB(2)\fP \fI(since C++11)\fP
   void splice_after( const_iterator pos, forward_list& other,     \fB(3)\fP \fI(since C++11)\fP
                      const_iterator it );
   void splice_after( const_iterator pos, forward_list&& other,    \fB(4)\fP \fI(since C++11)\fP
                      const_iterator it );
   void splice_after( const_iterator pos, forward_list& other,     \fB(5)\fP \fI(since C++11)\fP
                      const_iterator first, const_iterator last );
   void splice_after( const_iterator pos, forward_list&& other,    \fB(6)\fP \fI(since C++11)\fP
                      const_iterator first, const_iterator last );

   Moves elements from another forward_list to *this. The elements are inserted after
   the element pointed to by pos.

   No elements are copied. No iterators or references become invalidated. The iterators
   to the moved elements now refer into *this, not into other.

   1,2) Moves all elements from other into *this. The container other becomes empty
   after the operation.
   3,4) Moves the element pointed to by the iterator following it from other into
   *this. Has no effect if pos == it or if pos == ++it.
   5,6) Moves the elements in the range (first, last) from other into *this. The
   element pointed-to by first is not moved.

   The behavior is undefined if

     * get_allocator() != other.get_allocator(),
     * pos is neither before_begin() nor a dereferenceable iterator in
       [begin(), end()),
     * for overloads (1,2), *this and other refer to the same object,
     * for overloads (3,4), the iterator following it is not a dereferenceable iterator
       into other, or
     * for overloads (5,6),

     * (first, last) is not a valid range in other,
     * some iterators in (first, last) are not dereferenceable, or
     * pos is in (first, last).

.SH Parameters

   pos         - element after which the content will be inserted
   other       - another container to move the content from
   it          - iterator preceding the iterator to the element to move from other to
                 *this
   first, last - the range of elements to move from other to *this

.SH Return value

   \fI(none)\fP

.SH Exceptions

   Throws nothing.

.SH Complexity

   1,2) Linear in the size of other.
   3,4) Constant.
   5,6) Linear in std::distance(first, last).

.SH Example


// Run this code

 #include <cassert>
 #include <forward_list>

 int main()
 {
     using F = std::forward_list<int>;

     // Demonstrate the meaning of open range (first, last)
     // in overload (5): the first element of l1 is not moved.
     F l1 = {1, 2, 3, 4, 5};
     F l2 = {10, 11, 12};

     l2.splice_after(l2.cbegin(), l1, l1.cbegin(), l1.cend());
     // Not equivalent to l2.splice_after(l2.cbegin(), l1);
     // which is equivalent to
     // l2.splice_after(l2.cbegin(), l1, l1.cbefore_begin(), l1.end());

     assert((l1 == F{1}));
     assert((l2 == F{10, 2, 3, 4, 5, 11, 12}));

     // Overload (1)
     F x = {1, 2, 3, 4, 5};
     F y = {10, 11, 12};
     x.splice_after(x.cbegin(), y);
     assert((x == F{1, 10, 11, 12, 2, 3, 4, 5}));
     assert((y == F{}));

     // Overload (3)
     x = {1, 2, 3, 4, 5};
     y = {10, 11, 12};
     x.splice_after(x.cbegin(), y, y.cbegin());
     assert((x == F{1, 11, 2, 3, 4, 5}));
     assert((y == F{10, 12}));

     // Overload (5)
     x = {1, 2, 3, 4, 5};
     y = {10, 11, 12};
     x.splice_after(x.cbegin(), y, y.cbegin(), y.cend());
     assert((x == F{1, 11, 12, 2, 3, 4, 5}));
     assert((y == F{10}));
 }

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to          Behavior as published              Correct behavior
   LWG 2045 C++11      O(1) splicing could not be guaranteed if the behavior is
                       get_allocator() != other.get_allocator() undefined in this case

.SH See also

   merge         merges two sorted lists
                 \fI(public member function)\fP
   remove        removes elements satisfying specific criteria
   remove_if     \fI(public member function)\fP
   before_begin  returns an iterator to the element before beginning
   cbefore_begin \fI(public member function)\fP
